SD-2440 - fix: toc not loading on paragraphs by chittolinag · Pull Request #2706 · superdoc-dev/superdoc

chittolinag · 2026-04-02T16:11:56Z

Issue

Importing documents where the TOC field sits inline inside a paragraph crashed because the converter always emitted block tableOfContents nodes that expect paragraph parents. When that type of document is imported, SuperDoc crashes completely.

Solution

Detect when the parent disallows block nodes and encode the TOC within a paragraph block.

linear · 2026-04-02T16:12:00Z

SD-2440 BUG: Import fails on field-based list of tables/figures TOC paragraphs

github-actions · 2026-04-02T16:13:27Z

Status: PASS

The OOXML field character handling in this PR is spec-compliant.

The inline TOC decodes to the standard complex field structure defined in ECMA-376 §17.16.2:

w:fldChar (begin) → w:instrText (preserve) → w:fldChar (separate) → [content] → w:fldChar (end)

All three pieces check out:

w:fldCharType values begin, separate, end are the exact three valid values per §17.16.18
xml:space="preserve" on w:instrText matches the spec's own examples (§17.16.23) — preserving whitespace in field codes like TOC \h is correct
Field sequence is valid — separate is optional per spec, but including it (as the code does) is correct when there's result content following it

The only difference from the block variant is that the runs are returned as a flat array for injection into an existing paragraph rather than being wrapped in w:p elements. That's the right behavior for inline fields — the surrounding paragraph context is owned by the parent, not this node.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac0874bd59

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

…sed-list-of-tablesfigures-toc

caio-pizzol

@chittolinag tested with the original bug file + 13 other Word files. no crashes.

block TOCs decode children twice and the second pass can lose data — fix in the inline comment.

tableOfContentsInline was never triggered during testing, even with the original file. if no file produces it, the wrapping logic alone is the fix and the inline node type can be removed.

caio-pizzol · 2026-04-08T01:56:48Z

+    if (!exported) return [];
+    return Array.isArray(exported) ? exported : [exported];
+  });
+  const blockContentNodes = isInlineNode ? [] : tocContent.map((n) => exportSchemaToJson({ ...params, node: n }));


two things:

block TOCs decode every child twice — once for inlineContentNodes (thrown away) and once for blockContentNodes (kept). some decoders modify data as they go, so the second pass sees corrupted input. hyperlinks can get dropped. fix:

Suggested change

const blockContentNodes = isInlineNode ? [] : tocContent.map((n) => exportSchemaToJson({ ...params, node: n }));

const inlineContentNodes = isInlineNode

? tocContent.flatMap((n) => {

const exported = exportSchemaToJson({ ...params, node: n });

if (!exported) return [];

return Array.isArray(exported) ? exported : [exported];

})

: [];

const blockContentNodes = isInlineNode ? [] : tocContent.map((n) => exportSchemaToJson({ ...params, node: n }));

loaded the original Template_Test_Report.docx with debug logs — tableOfContentsInline was never produced. the paragraph wrapping at lines 42-49 is what prevents the crash. do you have a file that actually triggers the inline path?

Great catches. just fixed the 1st issue. I am now checking the 2nd issue you mentioned, it seems like there's also a problem when exporting the file (the opening in Word). I'll fix it.

Ok I've been trying to fix the export issue for a while now but no luck. I am pretty sure the export issue is unrelated though - after removing the TOC & re-exporting the document, the error persists.

If you agree, I'll file a separate ticket to handle it, but in the mean time I'll make sure to fix the issues you mentioned here in the review.

Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com>

…sed-list-of-tablesfigures-toc

…sed TOC (SD-2440)

caiopizzol

@chittolinag fix works, tested with the original file — document loads fine. nice simplification on the latest push.

added a few tests and uploaded the bug file to the test corpus so it's covered going forward.

superdoc-bot · 2026-04-09T18:50:14Z

🎉 This PR is included in vscode-ext v1.1.0-next.79

superdoc-bot · 2026-04-09T18:50:23Z

🎉 This PR is included in @superdoc-dev/react v1.0.0-next.33

The release is available on GitHub release

superdoc-bot · 2026-04-09T18:50:41Z

🎉 This PR is included in esign v2.2.0-next.37

The release is available on GitHub release

superdoc-bot · 2026-04-09T18:50:56Z

🎉 This PR is included in template-builder v1.3.0-next.39

The release is available on GitHub release

superdoc-bot · 2026-04-09T18:51:45Z

🎉 This PR is included in superdoc-cli v0.5.0-next.77

The release is available on GitHub release

superdoc-bot · 2026-04-09T18:51:50Z

🎉 This PR is included in superdoc v1.24.0-next.76

The release is available on GitHub release

superdoc-bot · 2026-04-09T18:53:53Z

🎉 This PR is included in superdoc-sdk v1.3.0-next.78

superdoc-bot · 2026-04-10T20:23:45Z

🎉 This PR is included in superdoc-sdk v1.4.0

superdoc-bot · 2026-04-10T20:33:59Z

🎉 This PR is included in superdoc v1.25.0

The release is available on GitHub release

superdoc-bot · 2026-04-10T22:29:49Z

🎉 This PR is included in superdoc-cli v0.6.0

The release is available on GitHub release

superdoc-bot · 2026-04-10T23:01:09Z

🎉 This PR is included in vscode-ext v2.3.0-next.1

superdoc-bot · 2026-04-10T23:01:34Z

🎉 This PR is included in template-builder v1.5.0-next.1

The release is available on GitHub release

superdoc-bot · 2026-04-10T23:01:37Z

🎉 This PR is included in esign v2.3.0-next.1

The release is available on GitHub release

fix: toc not loading on paragraphs

ac0874b

chittolinag changed the title ~~fix: toc not loading on paragraphs~~ SD-2440 - fix: toc not loading on paragraphs Apr 2, 2026

superdoc-bot bot added review: thorough review: careful and removed review: thorough labels Apr 2, 2026

chittolinag marked this pull request as ready for review April 2, 2026 19:03

chatgpt-codex-connector bot reviewed Apr 2, 2026

View reviewed changes

Comment thread ...editors/v1/core/super-converter/v3/handlers/sd/tableOfContents/tableOfContents-translator.js Outdated

chittolinag added 2 commits April 2, 2026 17:35

Merge branch 'main' into gabriel/sd-2440-bug-import-fails-on-field-ba…

7795ec9

…sed-list-of-tablesfigures-toc

Merge branch 'main' into gabriel/sd-2440-bug-import-fails-on-field-ba…

5083019

…sed-list-of-tablesfigures-toc

chittolinag requested review from VladaHarbour, caio-pizzol, luccas-harbour and tupizz April 2, 2026 20:48

missysuperdoc added the priority: high label Apr 6, 2026

caio-pizzol reviewed Apr 8, 2026

View reviewed changes

chittolinag and others added 2 commits April 8, 2026 14:41

fix: don't decode every child twice

2e6aabd

Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com>

fix: build

e4d3419

caio-pizzol assigned chittolinag Apr 9, 2026

chittolina added 4 commits April 9, 2026 12:43

refactor: removed unused code

8e31a4f

chore: small code tweaks

a8d623d

chore: small code tweaks

d935aa0

chore: removed unused code

139b17c

chittolinag requested a review from caio-pizzol April 9, 2026 15:54

chittolinag and others added 2 commits April 9, 2026 12:56

Merge branch 'main' into gabriel/sd-2440-bug-import-fails-on-field-ba…

e4216a3

…sed-list-of-tablesfigures-toc

test: add boundary unit tests and import regression test for field-ba…

2c5a073

…sed TOC (SD-2440)

caiopizzol approved these changes Apr 9, 2026

View reviewed changes

caio-pizzol added this pull request to the merge queue Apr 9, 2026

Merged via the queue into main with commit 90def7f Apr 9, 2026
54 checks passed

caio-pizzol deleted the gabriel/sd-2440-bug-import-fails-on-field-based-list-of-tablesfigures-toc branch April 9, 2026 18:08

superdoc-bot bot added the released on @next label Apr 9, 2026

superdoc-bot bot added the released on @latest label Apr 10, 2026

Conversation

chittolinag commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue

Solution

Uh oh!

linear bot commented Apr 2, 2026

Uh oh!

github-actions bot commented Apr 2, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

caio-pizzol Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

chittolinag Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

chittolinag Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

chittolinag Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

caiopizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 9, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

superdoc-bot bot commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

chittolinag commented Apr 2, 2026 •

edited

Loading